{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook we explore all the functionalities offered by `ranx.Qrels` and `ranx.Run`\n",
    "\n",
    "Please take a look ad the [documentation](https://amenra.github.io/ranx/qrels_and_run/) for the most up-to-date usage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First of all we need to install [ranx](https://github.com/AmenRa/ranx)\n",
    "\n",
    "Mind that the first time you run any ranx' functions they may take a while as they must be compiled first"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install -U ranx"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ranx import Qrels, Run"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Standard usage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The standard way of creating Qrels and Run is converting Python Dictionaries\n",
    "qrels_dict = {\"q_1\": {\"d_12\": 5, \"d_25\": 3}, \"q_2\": {\"d_11\": 6, \"d_22\": 1}}\n",
    "\n",
    "run_dict = {\n",
    "    \"q_1\": {\n",
    "        \"d_12\": 0.9,\n",
    "        \"d_23\": 0.8,\n",
    "        \"d_25\": 0.7,\n",
    "        \"d_36\": 0.6,\n",
    "        \"d_32\": 0.5,\n",
    "        \"d_35\": 0.4,\n",
    "    },\n",
    "    \"q_2\": {\n",
    "        \"d_12\": 0.9,\n",
    "        \"d_11\": 0.8,\n",
    "        \"d_25\": 0.7,\n",
    "        \"d_36\": 0.6,\n",
    "        \"d_22\": 0.5,\n",
    "        \"d_35\": 0.4,\n",
    "    },\n",
    "}\n",
    "\n",
    "qrels = Qrels(qrels_dict)\n",
    "run = Run(run_dict)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Qrels and Run have a `name` attribute which is used by other functionalities\n",
    "# of the library, you can change a Qrels or a Run name by changing its value\n",
    "# or providing it during creation (recommended)\n",
    "\n",
    "qrels.name = \"dataset_a\"\n",
    "run.name = \"bm25\"\n",
    "\n",
    "print(qrels.name)\n",
    "print(run.name)\n",
    "\n",
    "qrels = Qrels(qrels_dict, name=\"dataset_a\")\n",
    "run = Run(run_dict, name=\"bm25\")\n",
    "\n",
    "print(qrels.name)\n",
    "print(run.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import from Pandas DataFrame (same for Run)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas import DataFrame\n",
    "\n",
    "qrels_df = DataFrame.from_dict(\n",
    "    {\n",
    "        \"q_id\": [\"q_1\", \"q_1\", \"q_2\", \"q_2\"],\n",
    "        \"doc_id\": [\"d_12\", \"d_25\", \"d_11\", \"d_22\"],\n",
    "        \"score\": [5, 3, 6, 1],\n",
    "    }\n",
    ")\n",
    "\n",
    "qrels = Qrels.from_df(\n",
    "    df=qrels_df,\n",
    "    q_id_col=\"q_id\",\n",
    "    doc_id_col=\"doc_id\",\n",
    "    score_col=\"score\",\n",
    ")\n",
    "\n",
    "print(qrels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import from file (same for Run)\n",
    "\n",
    "Correct import behavior is inferred from the file extension: \".json\" -> \"json\", \".trec\" -> \"trec\", \".txt\" -> \"trec\".  \n",
    "Use the \"kind\" argument to override this behavior."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Download Qrels in JSON format and Qrels TREC-Style file\n",
    "import os\n",
    "import requests\n",
    "\n",
    "os.makedirs(\"notebooks/data\", exist_ok=True)\n",
    "\n",
    "with open(\"notebooks/data/small_qrels.json\", \"w\") as f:\n",
    "    master = f\"https://raw.githubusercontent.com/AmenRa/ranx/master/notebooks/data/small_qrels.json\"\n",
    "    f.write(requests.get(master).text)\n",
    "\n",
    "with open(\"notebooks/data/small_qrels.trec\", \"w\") as f:\n",
    "    master = f\"https://raw.githubusercontent.com/AmenRa/ranx/master/notebooks/data/small_qrels.trec\"\n",
    "    f.write(requests.get(master).text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import from JSON file\n",
    "qrels = Qrels.from_file(\"notebooks/data/small_qrels.json\")\n",
    "\n",
    "print(qrels)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import from TREC-Style file\n",
    "qrels = Qrels.from_file(\"notebooks/data/small_qrels.trec\")\n",
    "\n",
    "print(qrels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Save\n",
    "\n",
    "File format is inferred from the file extension: \".json\" -> \"json\", \".trec\" -> \"trec\", \".txt\" -> \"trec\".  \n",
    "Use the \"kind\" argument to override this behavior."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save as JSON file\n",
    "qrels.save(\"notebooks/data/small_qrels.json\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save as TREC-Style file\n",
    "qrels.save(\"notebooks/data/small_qrels.trec\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "692976b4e7dc85f192e7ff7f01132f0a9cfec5b2147f9c392e0014b728af08ff"
  },
  "kernelspec": {
   "display_name": "Python 3.7.12 ('ranx')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.12"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
